<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: ActionController::Caching::Fragments</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">ActionController::Caching::Fragments</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../../files/vendor/rails/actionpack/lib/action_controller/caching/fragments_rb.html">
                vendor/rails/actionpack/lib/action_controller/caching/fragments.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
Fragment caching is used for caching various blocks within templates
without caching the entire action as a whole. This is useful when certain
elements of an action change frequently or depend on complicated state
while other parts rarely change or can be shared amongst multiple parties.
The caching is done using the cache helper available in the Action View. A
template with caching might look something like:
</p>
<pre>
  &lt;b&gt;Hello &lt;%= @name %&gt;&lt;/b&gt;
  &lt;% cache do %&gt;
    All the topics in the system:
    &lt;%= render :partial =&gt; &quot;topic&quot;, :collection =&gt; Topic.find(:all) %&gt;
  &lt;% end %&gt;
</pre>
<p>
This cache will bind to the name of the action that called it, so if this
code was part of the view for the topics/list action, you would be able to
invalidate it using <tt><a
href="Fragments.html#M000882">expire_fragment</a>(:controller =&gt;
&quot;topics&quot;, :action =&gt; &quot;list&quot;)</tt>.
</p>
<p>
This default behavior is of limited use if you need to cache multiple
fragments per action or if the action itself is cached using
<tt>caches_action</tt>, so we also have the option to qualify the name of
the cached fragment with something like:
</p>
<pre>
  &lt;% cache(:action =&gt; &quot;list&quot;, :action_suffix =&gt; &quot;all_topics&quot;) do %&gt;
</pre>
<p>
That would result in a name such as &quot;/topics/list/all_topics&quot;,
avoiding conflicts with the action cache and with any fragments that use a
different suffix. Note that the URL doesn&#8216;t have to really exist or
be callable - the url_for system is just used to generate unique cache
names that we can refer to when we need to expire the cache.
</p>
<p>
The expiration call for this example is:
</p>
<pre>
  expire_fragment(:controller =&gt; &quot;topics&quot;, :action =&gt; &quot;list&quot;, :action_suffix =&gt; &quot;all_topics&quot;)
</pre>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000882">expire_fragment</a>&nbsp;&nbsp;
      <a href="#M000878">fragment_cache_key</a>&nbsp;&nbsp;
      <a href="#M000881">fragment_exist?</a>&nbsp;&nbsp;
      <a href="#M000880">read_fragment</a>&nbsp;&nbsp;
      <a href="#M000879">write_fragment</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">





      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M000882" class="method-detail">
        <a name="M000882"></a>

        <div class="method-heading">
          <a href="#M000882" class="method-signature">
          <span class="method-name">expire_fragment</span><span class="method-args">(key, options = nil)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Name can take one of three forms:
</p>
<ul>
<li>String: This would normally take the form of a path like
&quot;pages/45/notes&quot;

</li>
<li>Hash: Is treated as an implicit call to url_for, like { :controller =&gt;
&quot;pages&quot;, :action =&gt; &quot;notes&quot;, :id =&gt; 45 }

</li>
<li>Regexp: Will destroy all the matched fragments, example:

<pre>
  %r{pages/\d*/notes}
</pre>
<p>
Ensure you do not specify start and finish in the regex (^$) because the
actual filename matched looks like ./cache/filename/path.cache Regexp
expiration is only supported on caches that can iterate over all keys
(unlike memcached).
</p>
</li>
</ul>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000882-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000882-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/fragments.rb, line 95</span>
 95:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">expire_fragment</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
 96:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">cache_configured?</span>
 97: 
 98:         <span class="ruby-identifier">key</span> = <span class="ruby-identifier">key</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Regexp</span>) <span class="ruby-operator">?</span> <span class="ruby-identifier">key</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">fragment_cache_key</span>(<span class="ruby-identifier">key</span>)
 99: 
100:         <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">key</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Regexp</span>)
101:           <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">benchmark</span> <span class="ruby-node">&quot;Expired fragments matching: #{key.source}&quot;</span> <span class="ruby-keyword kw">do</span>
102:             <span class="ruby-identifier">cache_store</span>.<span class="ruby-identifier">delete_matched</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span>)
103:           <span class="ruby-keyword kw">end</span>
104:         <span class="ruby-keyword kw">else</span>
105:           <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">benchmark</span> <span class="ruby-node">&quot;Expired fragment: #{key}&quot;</span> <span class="ruby-keyword kw">do</span>
106:             <span class="ruby-identifier">cache_store</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span>)
107:           <span class="ruby-keyword kw">end</span>
108:         <span class="ruby-keyword kw">end</span>
109:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000878" class="method-detail">
        <a name="M000878"></a>

        <div class="method-heading">
          <a href="#M000878" class="method-signature">
          <span class="method-name">fragment_cache_key</span><span class="method-args">(key)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Given a key (as described in <tt><a
href="Fragments.html#M000882">expire_fragment</a></tt>), returns a key
suitable for use in reading, writing, or expiring a cached fragment. If the
key is a hash, the generated key is the return value of url_for on that
hash (without the protocol). All keys are prefixed with &quot;views/&quot;
and uses ActiveSupport::Cache.expand_cache_key for the expansion.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000878-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000878-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/fragments.rb, line 33</span>
33:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">fragment_cache_key</span>(<span class="ruby-identifier">key</span>)
34:         <span class="ruby-constant">ActiveSupport</span><span class="ruby-operator">::</span><span class="ruby-constant">Cache</span>.<span class="ruby-identifier">expand_cache_key</span>(<span class="ruby-identifier">key</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Hash</span>) <span class="ruby-operator">?</span> <span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">key</span>).<span class="ruby-identifier">split</span>(<span class="ruby-value str">&quot;://&quot;</span>).<span class="ruby-identifier">last</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">key</span>, <span class="ruby-identifier">:views</span>)
35:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000881" class="method-detail">
        <a name="M000881"></a>

        <div class="method-heading">
          <a href="#M000881" class="method-signature">
          <span class="method-name">fragment_exist?</span><span class="method-args">(key, options = nil)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Check if a cached fragment from the location signified by <tt>key</tt>
exists (see <tt><a href="Fragments.html#M000882">expire_fragment</a></tt>
for acceptable formats)
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000881-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000881-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/fragments.rb, line 76</span>
76:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">fragment_exist?</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
77:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">cache_configured?</span>
78: 
79:         <span class="ruby-identifier">key</span> = <span class="ruby-identifier">fragment_cache_key</span>(<span class="ruby-identifier">key</span>)
80: 
81:         <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">benchmark</span> <span class="ruby-node">&quot;Cached fragment exists?: #{key}&quot;</span> <span class="ruby-keyword kw">do</span>
82:           <span class="ruby-identifier">cache_store</span>.<span class="ruby-identifier">exist?</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span>)
83:         <span class="ruby-keyword kw">end</span>
84:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000880" class="method-detail">
        <a name="M000880"></a>

        <div class="method-heading">
          <a href="#M000880" class="method-signature">
          <span class="method-name">read_fragment</span><span class="method-args">(key, options = nil)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Reads a cached fragment from the location signified by <tt>key</tt> (see
<tt><a href="Fragments.html#M000882">expire_fragment</a></tt> for
acceptable formats)
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000880-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000880-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/fragments.rb, line 65</span>
65:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">read_fragment</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
66:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">cache_configured?</span>
67: 
68:         <span class="ruby-identifier">key</span> = <span class="ruby-identifier">fragment_cache_key</span>(<span class="ruby-identifier">key</span>)
69: 
70:         <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">benchmark</span> <span class="ruby-node">&quot;Cached fragment hit: #{key}&quot;</span> <span class="ruby-keyword kw">do</span>
71:           <span class="ruby-identifier">cache_store</span>.<span class="ruby-identifier">read</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">options</span>)
72:         <span class="ruby-keyword kw">end</span>
73:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000879" class="method-detail">
        <a name="M000879"></a>

        <div class="method-heading">
          <a href="#M000879" class="method-signature">
          <span class="method-name">write_fragment</span><span class="method-args">(key, content, options = nil)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Writes <tt>content</tt> to the location signified by <tt>key</tt> (see
<tt><a href="Fragments.html#M000882">expire_fragment</a></tt> for
acceptable formats)
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000879-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000879-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/caching/fragments.rb, line 52</span>
52:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">write_fragment</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">content</span>, <span class="ruby-identifier">options</span> = <span class="ruby-keyword kw">nil</span>)
53:         <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">cache_configured?</span>
54: 
55:         <span class="ruby-identifier">key</span> = <span class="ruby-identifier">fragment_cache_key</span>(<span class="ruby-identifier">key</span>)
56: 
57:         <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">class</span>.<span class="ruby-identifier">benchmark</span> <span class="ruby-node">&quot;Cached fragment miss: #{key}&quot;</span> <span class="ruby-keyword kw">do</span>
58:           <span class="ruby-identifier">cache_store</span>.<span class="ruby-identifier">write</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">content</span>, <span class="ruby-identifier">options</span>)
59:         <span class="ruby-keyword kw">end</span>
60: 
61:         <span class="ruby-identifier">content</span>
62:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>